User Defined Model

Developing Applications Using The SoftwareShield System > Creating Licensing Solutions > Available License Models > IronWrapping™ License Models > User Defined License Model Design

## User Defined License Model Design

The User Defined License Model plugged into the License Managers IronWrapping system becomes a first class citizen of the system. It is sometimes referred to as a ”System DLL”. Note that this documentation refers to the term ”YCore” which is the internal name for ”IronWrapping” &endash; they are the same thing.

The User Defined License Model must expose an special entry point like this:

Delphi:
procedure YShieldEntry(appSrv: IAppSrv); stdcall;

C++:
void WINAPI __declspec(dllexport) YShieldEntry(IAppSrv: appSrv);

This entry point is called in the main thread by the YShield::loader when all of the embedded modules are loaded in memory successfully, and just before the host's OEP (Original Entry Point) get control. All dependent APIs are resolved, all YShield system stuffs are ready to provide services, so it's safe to do anything. On the other hand, the standard DllMain() entry point is not a safe place to call many Windows APIs, such as OLE functions since the system is still in a unstable loading state.

What to do here: Being a system module, there is certainly some work to do at this point. See below for a step-by-step procedure of what your License Model must do.

### When your User Defined License Module (DLL) is initialized, or at the first opportunity, you must initialize objects and get ready to execute in two steps:

1. Create an instance of the ClientProtector (COM) object included in the DRM Kit and connect any event handlers required. See the help file section on ”Linking to the ClientProtector in your Application for help”. Note that while you are developing your User Defined License Model, you can use and debug in your regular IDE and link to the ClientProtector COM server in the regular way. When you eventually plug-in your User Defined License Model, the ClientProtector COM server will be embedded and access to it 100% virtualized &endash; so there is no change necessary in your code.

   Note it is possible to defer the creation of this object until the YShieldEntry is actually called (see below). However, our sample code provided performs the creation here. Also note that you will need module ”lifetime” of the object anyway because the IronWrapping system will call back into your code when the host program shuts down and it is critical that your User Defined License Model uses the *same single* instance of the ClientProtector for the whole execution.

2. Call installEventCallback() on the IAppSvr interface. The interface pointer is passed to your YShieldEntry function as a ”IAppSrv” type. (Your code will have to include a reference to the header file for this interface). When you call this function you ”register” your own event call-back with the IronWrapping system. This call-back function in your code will be called by the IronWrapping system when the process is exiting to allow your License Model to display certain UI *after* the program exits (for example to display a reminder that there are only a few minutes left in a trial and the user should purchase the product).

### When your YShieldEntry function is called (by the IronWrapping system / AKA: YShield), you must perform your ”start up” licensing functionality, relying on the ClientProtector to do all the license manipulation. Here you may show UI to the user to give/get feedback and here you will decide if the program will be allowed to run or not. You do this by performing these seven steps:

1. Call SetYCoreInterface() on the ClientProtector, passing the YCore interface (IronWrapping Interface). The interface pointer is passed to your YShieldEntry function as a ”IAppSrv” type. This allows the ClientProtector to directly communicate with the IronWrapping system in order to set encryption keys and other functionality which your License Model does not directly need to know about.

2. Call StartUp() on the ClientProtector. This phase of processing is identical to the well-documented methods of using the ClientProtector outside of the system. See the help for more information on StartUp.

3. Respond to synchronous events (if necessary) while StartUp executes. Refer to the help for more information on the events the ClientProtector may raise during StartUp.

4. Deal with the result of the StartUp call. In most cases the result (”return_code”) of the StartUp will give your User Defined License Model enough information to allow processing to continue of not.

5. Call any other functions on the ClientProtector interface to perform any necessary activation of other operations before either shutting down or allowing the program to run.

6. Display any and all necessary UI in order to communicate with the user. For example, you may wish to show a reminder screen that tells the user how many minutes of trial time they have left. Or, you may need to present the user with a dialog so they can enter their Serial Number prior to your code trying to activating it using a call to AutoActivateSerialNumber() on the ClientProtector (for example).

7. If your User Defined Model determines that the program should not run, it must call ExitProcess(0). It is important that this is the sole method that the User Defined License Model uses and the parameter value is zero (0).

IAppSrv: IronWrapping Interface of public services

Your code will need to include the header file for IAppSrv so that it may (at least) call installEventCallBack() on the interface. This header is currently provided in Delphi and Borland C++ Builder (as an import from the Delphi). The interface is simple so parting it to a new language is fairly straightforward.

The interface is defined in: AppSvrIntf.pas (Delphi source) and AppSrvIntf.hpp (BCB import).

### Sample Code

Sample Code for the User Defined Models can be found under the:

<SoftwareShieldInstallPath>\SampleCode\IW_SampleUserDefined

There are sample code for the following models:

Lease Model - This model will start off with a 30 day trial. After 30 days, the client would need to purchase a 365-days lease. After 365 days, the lease will expire and the user must renew it.

The sample code includes:

- License Model DLL - defines the User Interface and behavior of the model

- Test Driver - a simple application used to test the License Model with the IDE.

- License Project (LPJ) - used by the License Manager to compile a License file

- SampleExe - a simple program used as a host for the license project

- HTMLForms - simple html files that are used as the UI for the sample program

- Original License File - folder that stores the license projects and file for the models

- YShieldInterfaceHeaderFiles - header files used by the YShieldInterface

- SSCProt Header - header file for the ClientProtector

If you intend to use the test driver, ensure that the file path to the User Defined Model dll is correct within the test driver code. You would also need a compiled license file in the same directory as the test driver (unless the file path to the license file has been changed with in the User Defined Model)

If you intend to use online activation, make sure that you configure the project to use CheckPoint and setup a CheckPoint Server.